{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Doyle-Fuller-Newman Model (DFN)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Model Equations"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The DFN comprises equations for charge and mass conservation in the solid the solid and electrolyte, and also prescribes behaviour for the electrochemical reactions occurring on the interface between the solid an electrolyte. For more information please see [[2]](#References) or other standard texts. \n",
    "\n",
    "Below we summarise the model, with all parameters give in the table at the end of this notebook. Here we use a roman subscript $\\text{k} \\in \\text{n, s, p}$ is used to denote the regions negative electrode, separator, and positive electrode, respectively.\n",
    "\n",
    "The model equations for the DFN read: \n",
    "\n",
    "#### Charge conservation:\n",
    "$$\n",
    "    \\frac{\\partial i_{\\text{e,k}}}{\\partial x} = \\begin{cases}\n",
    "                                                      a_{\\text{k}}j_{\\text{k}}, \\quad &\\text{k} = \\text{n, p}\\\\ \n",
    "                                                      0, \\qquad &\\text{k} = \\text{s}\n",
    "                                                \\end{cases},\n",
    "$$\n",
    "\n",
    "$$\n",
    "    i_{\\text{e,k}} = \\epsilon_{\\text{k}}^{\\text{b}} \\kappa_{\\text{e}}(c_{\\text{e,k}}) \\left( - \\frac{\\partial \\phi_{\\text{e,k}}}{\\partial x} + 2(1-t^+)\\frac{RT}{F}\\frac{\\partial}{\\partial x}\\left(\\log(c_{\\text{e,k}})\\right)\\right), \\text{k} \\in \\text{n, s, p}, \\\\ \n",
    "    I-i_{\\text{e,k}} = - \\sigma_{\\text{k}} \\frac{\\partial \\phi_{\\text{e,k}}}{\\partial x}, \\text{k} \\in \\text{n, s, p}.\n",
    "$$\n",
    "\n",
    "#### Mass conservation:\n",
    "$$\n",
    "\\epsilon_{\\text{k}} \\frac{\\partial c_{\\text{e,k}}}{\\partial t} = -\\frac{\\partial N_{\\text{e,k}}}{\\partial x} + \\frac{1}{F}\\frac{\\partial i_{\\text{e,k}}}{\\partial x}, \\text{k} \\in \\text{n, s, p},\\\\\n",
    "N_{\\text{e,k}} = -\\epsilon_{\\text{k}}^{\\text{b}} D_{\\text{e}}(c_{\\text{e,k}}) \\frac{\\partial c_{\\text{e,k}}}{\\partial x} +  \\frac{t^+}{F} i_{\\text{e,k}},\n",
    "\\\\ \\text{k} \\in \\text{n, s, p}, \\\\\n",
    "\\frac{\\partial c_{\\text{s,k}}}{\\partial t} = -\\frac{1}{r_{\\text{k}}^2} \\frac{\\partial}{\\partial r_{\\text{k}}} \\left(r_{\\text{k}}^2 N_{\\text{s,k}}\\right), \\\\ \\text{k} \\in \\text{n, p},\\\\\n",
    "N_{\\text{s,k}} = -D_{\\text{s,k}}(c_{\\text{s,k}}) \\frac{\\partial c_{\\text{s,k}}}{\\partial r_{\\text{k}}}, \\\\ \\text{k} \\in \\text{n, p}.\n",
    "$$\n",
    "\n",
    "\n",
    "#### Electrochemical reactions:\n",
    "$$\n",
    "j_{\\text{k}} = 2 j_{\\text{0,k}} \\sinh\\left(\\frac{ F\\eta_{\\text{k}}}{2RT} \\right), \\\\ \\text{k} \\in \\text{n, p}, \\\\\n",
    "j_{\\text{0,k}} = c_{\\text{s,k}}^{1/2} (1-c_{\\text{s,k}})^{1/2}c_{\\text{e,k}}^{1/2}\\big|_{r_{\\text{k}}=1}, \\\\ \\text{k} \\in \\text{n, p}, \\\\\n",
    "\\eta_{\\text{k}} = \\phi_{\\text{s,k}} - \\phi_{\\text{e,k}} - U_{\\text{k}}(c_{\\text{s,k}}\\big|_{r_{\\text{k}}=1}), \\\\ \\text{k} \\in \\text{n, p}.\n",
    "$$\n",
    "\n",
    "\n",
    "These are to be solved subject to the following boundary conditions:\n",
    "\n",
    "#### Current:\n",
    "$$\n",
    "i_{\\text{e,n}}\\big|_{x=0} = 0, \\quad i_{\\text{e,p}}\\big|_{x=L}=0,  \\\\\n",
    "\\phi_{\\text{e,n}}\\big|_{x=L_{\\text{n}}} = \\phi_{\\text{e,s}}\\big|_{x=L_{\\text{n}}}, \\quad i_{\\text{e,n}}\\big|_{x=L_{\\text{n}}} = i_{\\text{e,s}}\\big\\vert_{x=L_{\\text{n}}} = I, \\\\ \n",
    "\\phi_{\\text{e,s}}\\big|_{x=L-L_{\\text{p}}} = \\phi_{\\text{e,p}}\\big|_{x=L-L_{\\text{p}}}, \\quad \n",
    "    i_{\\text{e,s}}\\big|_{x=L-L_{\\text{p}}} = i_{\\text{e,p}}\\big|_{x=L-L_{\\text{p}}} = I.\n",
    "$$\n",
    "\n",
    "#### Concentration in the electrolyte:\n",
    "$$\n",
    "N_{\\text{e,n}}\\big|_{x=0} = 0, \\quad N_{\\text{e,p}}\\big|_{x=L}=0,\\\\ \n",
    "c_{\\text{e,n}}\\big|_{x=L_{\\text{n}}} = c_{\\text{e,s}}|_{x=L_{\\text{n}}}, \\quad N_{\\text{e,n}}\\big|_{x=L_{\\text{n}}}=N_{\\text{e,s}}\\big|_{x=L_{\\text{n}}}, \\\\\n",
    "c_{\\text{e,s}}|_{x=L-L_{\\text{p}}}=c_{\\text{e,p}}|_{x=L-L_{\\text{p}}}, \\quad N_{\\text{e,s}}\\big|_{x=L-L_{\\text{p}}}=N_{\\text{e,p}}\\big|_{x=L-L_{\\text{p}}}.\n",
    "$$\n",
    "\n",
    "####  Concentration in the electrode active material:\n",
    "$$\n",
    "N_{\\text{s,k}}\\big|_{r_{\\text{k}}=0} = 0, \\quad \\text{k} \\in \\text{n, p}, \\quad \\ \\ N_{\\text{s,k}}\\big|_{r_{\\text{k}}=R_{\\text{k}}} = \\frac{j_{\\text{k}}}{F}, \\quad \\text{k} \\in \\text{n, p}.\n",
    "$$\n",
    "\n",
    "#### Reference potential:\n",
    "$$\\phi_{\\text{s,cn}} = 0, \\quad  \\boldsymbol{x} \\in \\partial \\Omega_{\\text{tab,n}}.$$\n",
    "\n",
    "\n",
    "#### And the initial conditions:\n",
    "\n",
    "$$\n",
    "c_{\\text{s,k}}(x,r,0) = c_{\\text{s,k,0}}, \\quad \\text{k} \\in \\text{n, p},\\\\\n",
    "c_{\\text{e,k}}(x,0) = c_{\\text{e,0}}, \\quad \\text{k} \\in \\text{n, s, p}. \n",
    "$$\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example solving DFN using PyBaMM"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below we show how to solve the DFN model, using the default geometry, mesh, parameters, discretisation and solver provided with PyBaMM. For a more detailed example, see the notebook on the [SPM](https://github.com/pybamm-team/PyBaMM/blob/develop/docs/source/examples/notebooks/models/SPM.ipynb).\n",
    "\n",
    "In order to show off all the different points at which the process of setting up and solving a model in PyBaMM can be customised we explicitly handle the stages of choosing a geometry, setting parameters, discretising the model and solving the model. However, it is often simpler in practice to use the `Simulation` class, which handles many of the stages automatically, as shown [here](../simulations_and_experiments/simulation-class.ipynb).\n",
    "\n",
    "First we need to import pybamm, along with numpy which we will use in this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33mWARNING: You are using pip version 21.0.1; however, version 21.1.2 is available.\n",
      "You should consider upgrading via the '/home/user/Documents/PyBaMM/env/bin/python3.8 -m pip install --upgrade pip' command.\u001b[0m\n",
      "Note: you may need to restart the kernel to use updated packages.\n"
     ]
    }
   ],
   "source": [
    "%pip install \"pybamm[plot,cite]\" -q    # install PyBaMM if it is not installed\n",
    "import numpy as np\n",
    "\n",
    "import pybamm"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We then load the DFN model and default geometry, and process them both using the default parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load model\n",
    "model = pybamm.lithium_ion.DFN()\n",
    "\n",
    "# create geometry\n",
    "geometry = model.default_geometry\n",
    "\n",
    "# load parameter values and process model and geometry\n",
    "param = model.default_parameter_values\n",
    "param.process_model(model)\n",
    "param.process_geometry(geometry)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The next step is to set the mesh and discretise the model. Again, we choose the default settings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set mesh\n",
    "mesh = pybamm.Mesh(geometry, model.default_submesh_types, model.default_var_pts)\n",
    "\n",
    "# discretise model\n",
    "disc = pybamm.Discretisation(mesh, model.default_spatial_methods)\n",
    "disc.process_model(model);"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The model is now ready to be solved. We select the default DAE solver for the DFN. Note that in order to successfully solve the system of DAEs we are required to give consistent initial conditions. This is handled automatically by PyBaMM during the solve operation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# solve model\n",
    "solver = model.default_solver\n",
    "t_eval = np.linspace(0, 3600, 300)  # time in seconds\n",
    "solution = solver.solve(model, t_eval)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get a quick overview of the model outputs we can use the QuickPlot class, which plots a common set of useful outputs. The method `Quickplot.dynamic_plot` makes a slider widget."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "f5e601cafbab40808734ca87e4c64de2",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.0, description='t', max=1.0, step=0.01), Output()), _dom_classes=('w…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "quick_plot = pybamm.QuickPlot(\n",
    "    solution, [\"Positive electrode interfacial current density [A.m-2]\"]\n",
    ")\n",
    "quick_plot.dynamic_plot();"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "The relevant papers for this notebook are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1] Joel A. E. Andersson, Joris Gillis, Greg Horn, James B. Rawlings, and Moritz Diehl. CasADi – A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1):1–36, 2019. doi:10.1007/s12532-018-0139-4.\n",
      "[2] Marc Doyle, Thomas F. Fuller, and John Newman. Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of the Electrochemical society, 140(6):1526–1533, 1993. doi:10.1149/1.2221597.\n",
      "[3] Charles R. Harris, K. Jarrod Millman, Stéfan J. van der Walt, Ralf Gommers, Pauli Virtanen, David Cournapeau, Eric Wieser, Julian Taylor, Sebastian Berg, Nathaniel J. Smith, and others. Array programming with NumPy. Nature, 585(7825):357–362, 2020. doi:10.1038/s41586-020-2649-2.\n",
      "[4] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149/2.0341915jes.\n",
      "[5] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). ECSarXiv. February, 2020. doi:10.1149/osf.io/67ckj.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "pybamm.print_citations()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "dev",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.4"
  },
  "vscode": {
   "interpreter": {
    "hash": "bca2b99bfac80e18288b793d52fa0653ab9b5fe5d22e7b211c44eb982a41c00c"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
